Inside Macintosh: Mac OS 8 Toolbox Reference /

Chapter 2 - Control Manager Reference / Control Manager Functions

Handling Events in Controls /

HandleControlClick

NEW WITH THE APPEARANCE MANAGER

Follows and responds to cursor movements in a control while the mouse button is down and determines the control part in which the next mouse-up event occurs.

pascal ControlPartCode HandleControlClick (
                     ControlHandle inControl,
                     Point inWhere,
                     SInt16 inModifiers,
                     ControlActionUPP inAction);

inControl

On input, a handle to the control in which the mouse-down event occurred. Pass the control handle returned by FindControl or FindControlUnderMouse.

inWhere

A point, specified in local coordinates, where the mouse-down event occurred. Supply the same point you passed to FindControl or FindControlUnderMouse.

inModifiers

Information about the state of the modifier keys and the mouse button at the time the event was posted.

inAction

On input, a pointer to an action function defining what action your application takes while the user holds down the mouse button. The value of the inAction parameter can be a valid procPtr, nil, or -1. A value of -1 indicates that the control should either perform auto tracking, or if it is incapable of doing so, do nothing (like nil). For custom controls, what you pass in this parameter depends on how you define the control. If the part index is greater than 128, the pointer must be of type DragGrayRegionUPP unless the control supports live feedback, in which case it should be a ControlActionUPP.

function result

Returns a value of type ControlPartCode identifying the control's part; see "Control Part Code Constants".

DISCUSSION

Call the HandleControlClick function after a call to FindControl or FindControlUnderMouse. The HandleControlClick function should be called instead of TrackControl to follow the user's cursor movements in a control and provide visual feedback until the user releases the mouse button. Unlike TrackControl, HandleControlClick allows modifier keys to be passed in so that the control may use these if the control (such as a list box or editable text field) is set up to handle its own tracking.

The visual feedback given by HandleControlClick depends on the control part in which the mouse-down event occurs. When highlighting is appropriate, for example, HandleControlClick highlights the control part (and removes the highlighting when the user releases the mouse button). When the user holds down the mouse button while the cursor is in an indicator (such as the scroll box of a scroll bar) and moves the mouse, HandleControlClick responds by dragging a dotted outline or a ghost image of the indicator. If the user releases the mouse button when the cursor is in an indicator such as the scroll box, HandleControlClick calls the control definition function to reposition the indicator.

While the user holds down the mouse button with the cursor in one of the standard controls, HandleControlClick performs the following actions, depending on the value you pass in the parameter inAction.

• If you pass nil in the inAction parameter, HandleControlClick uses no action function and therefore performs no additional actions beyond highlighting the control or dragging the indicator. This is appropriate for push buttons, checkboxes, radio buttons, and the scroll box of a scroll bar.
• If you pass a pointer to an action function in the inAction parameter, it must define some action that your application repeats as long as the user holds down the mouse button. This is appropriate for the scroll arrows and gray areas of a scroll bar.
• If you pass (ControlActionUPP)-1L in the inAction parameter, HandleControlClick looks in the contrlAction field of the control structure for a pointer to the control's action function. This is appropriate when you are tracking the cursor in a pop-up menu. You can call GetControlAction to determine the value of this field, and you can call SetControlAction to change this value. If the contrlAction field of the control structure contains a function pointer, HandleControlClick uses the action function it points to; if the field of the control structure also contains the value (ControlActionUPP)-1L, HandleControlClick calls the control definition function to perform the necessary action; you may wish to do this if you define your own control definition function for a custom control. If the field of the control structure contains the value nil, HandleControlClick performs no action.

Note

For 'CDEF' resources that implement custom dragging, you usually call HandleControlClick, which returns 0 regardless of the user's changes of the control setting. To avoid this, you should use another method to determine whether the user has changed the control setting, for instance, comparing the control's value before and after your call to HandleControlClick.

SEE ALSO

MyActionProc.

"Appearance Manager Gestalt Selector Constants".